IEMappedFile

INHERITS FROM	Object

WRITTEN BY	Montgomery Zukowski, Intuitive Edge

SUPPORT	monty@IntuitiveEdge.com

Version 1.0.

CLASS DESCRIPTION

	IEMappedFile is a public domain class.  It is designed as a central resource to map files into memory and make sure that only one object corresponds to one filename.  It encapsulates the following information:
	-the filename (which has been NXUniqueString'ed)
	-the open file descriptor
	-the pointer to the memory which is mapped to the file
	-the size of the file
	-the last modify time of the file
	
	The factory object keeps a HashTable of filenames and objects to insure that only one instance is created for a given filename.  	There are two methods which return the pointer to the memory map.  The -data method just returns the pointer.  The -dataUpdated method first checks to see if the file has been modified, and if it has it remaps the file and returns the data pointer.
	This is a read only object and does not support writing memory to disk, or even writing to memory.
	Internal methods are denoted by a leading underscore, such as _initFromName.  These methods are only meant to be called from within the object's methods.
	Feel free to use and modify as long as you acknowledge me (Monty Zukowski) as the original author.

INSTANCE VARIABLES

Declared in NumberedExtensionManager	
	int	fd;
	int	size;
	NXAtom	name;
	void	*data;
	time_t	lastModifyTime;

fd	The file descriptor of the open read only file.
size	The size of the file.
name	The name of the file.
data	A pointer to the memory map of the file.
lastModifyTime	The last modify time obtained during +newForFilename or -dataUpdated.

METHOD TYPES

Class Methods
+ instances
+ newForFilename:

Data
-data
-dataUpdated

File information

- fd
- size
- name
- lastModifyTime

Archiving

-write:
-read:
-finishUnarchiving

Internal Methods	
+_removeFromHashTable:
+_addName::
-_initFromName:
-_inactivate

CLASS METHODS
	+ instances
+(HashTable *) instances

Returns the HashTable which holds the (NXAtom) names as keys and the corresponding (id) instances as the values.

	+ newForFilename:
+ newForFilename:(const char *) filename

 Returns an instance for the given filename.  The name of the instance = NXUniqueString(filename).  If an instance for filename already exists that instance is returned.  Otherwise a new instance is created.  If there are any problems opening or mapping filename, nil is returned.

	+_removeFromHashTable:
+_removeFromHashTable:(IEMappedFile *)obj;

Internal method which removes obj from the class' HashTable.   Returns self;

	+_addName::
+_addName:(NXAtom) theName andObject:obj;

Internal method which adds theName and obj to the class' HashTable if they are not already in the HashTable and returns self.  If theName is already in the HashTable, it is not inserted and nil is returned.

INSTANCE METHODS
	-data
-(const void *) data

Returns the pointer to the memory map of the file.  May be NULL resulting from a -dataUpdated or -read: method inactivating the instance.

	-dataUpdated
-(const void *) dataUpdated
Tries to synchronize the instance with the file on disk.   Remaps the file if it has been modified since lastModifyTime.  If the instance's memory map has become inactive it tries to reinitialize the instance.  If there are any problems, the instance is inactivated and NULL is returned.  Always check the return value before using, and -size so you don't go out of bounds.

	- fd
-(int) fd

Returns the file descriptor for the open file which is memory mapped.

	-finishUnarchiving
-finishUnarchiving
Inherited from Object and implemented to insure that only one instance of IEMappedFile exists for any filename.

	-_inactivate
-_inactivate
Internal method used to inactivate an instance.

	-_initFromName
-_initFromName
Internal method used to initialize the fd, data, size, and lastModifyTime instance variables from the name instance variable.

	- lastModifyTime
-(time_t) lastModifyTime
Returns the modify time (st_mtime from the stat struct) from when the file was last mapped by the instance.

	- name
-(NXAtom) name
Returns the filename this instance represents.

	-read:
-read:(NXTypedStream *) typedStream
Reads an IEMappedFile from typedStream.  If there are any problems with opening or mapping the file, the instance may be inactivated.

	- size
-(int) size
Returns the size in bytes of the memory map of the file.

	-write:
-write:(NXTypedStream *) typedStream
Writes an IEMapedFile instance to typedStream.

CONSTANTS AND DEFINED TYPES

None.